<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GrPPI: Filter pattern</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="logo.svg"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">GrPPI
   &#160;<span id="projectnumber">0.3.1</span>
   </div>
   <div id="projectbrief">Generic and Reusable Parallel Pattern Interface</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Filter pattern </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The <b>filter</b> (or <em>stream filter</em>) is a streaming pattern that discards items from a data stream based on a predicate, so that only data items satisfying (keep) or dissatisfying (discard) the predicate are passed to the next stage. This streaming pattern can only be used inside another pattern and consequently does not take an execution policy itself, but uses the execution policy of its enclosing pattern.</p>
<p>The interface to the <b>filter</b> pattern is provided by functions <code><a class="el" href="group__filter__pattern.html#gabc3773f21c14b2272c5ff404b4e9f8c2" title="Invoke Filter pattern on a data stream that can be composed in other streaming patterns. This function keeps in the stream only those items that satisfy the predicate. ">grppi::keep()</a></code> and <code><a class="el" href="group__filter__pattern.html#gab8bcbdf6de8a446a291162ee4e7f7944" title="Invoke Filter pattern on a data stream that can be composed in other streaming patterns. This function discards from the stream those items that satisfy the predicate. ">grppi::discard()</a></code>.</p>
<div class="fragment"><div class="line"><a class="code" href="group__pipeline__pattern.html#gacb5843d0d5fd08d02fa4679b81b9d918">grppi::pipeline</a>(exec,</div><div class="line">  stage1,</div><div class="line">  <a class="code" href="group__filter__pattern.html#gabc3773f21c14b2272c5ff404b4e9f8c2">grppi::keep</a>(predicate1),</div><div class="line">  <a class="code" href="group__filter__pattern.html#gab8bcbdf6de8a446a291162ee4e7f7944">grppi::discard</a>(predicate2),</div><div class="line">  stage3,</div><div class="line">  stage4);</div></div><!-- fragment --><h2>Stream filter variants</h2>
<p>There is a single variant:</p>
<ul>
<li><em>Composable filter</em>: Defines a filter that can be used as a building block by another pattern (e.g. a pipeline).</li>
</ul>
<h2>Key elements in stream filter</h2>
<p>The central element in a <b>filter</b> is the <b>Predicate</b>. The operation may be any C++ callable entity. This operation, is a unary operation taking a data item and returning value that is contextually convertible to <code>bool</code>. Thus, a predicate <code>pred</code> is any operation, that given a value <code>x</code> of type <code>T</code>, makes the following valid:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (predicate(item)) { <span class="comment">/*...*/</span> }. </div><div class="line"><span class="keywordflow">if</span> (!predicate(item)) { <span class="comment">/*...*/</span> }. </div></div><!-- fragment --><h2>Details on stream filter variants</h2>
<h3>Composable filter</h3>
<p>A composable filter has a single element:</p>
<ul>
<li>A <b>Predicate</b> filtering values.</li>
</ul>
<p>The input values will be generated by the upper level pattern, which will be also responsible for consuming the output values. </p><hr/>
<p> <b>Example</b>: A filter stage in a pipeline. </p><div class="fragment"><div class="line"><a class="code" href="group__pipeline__pattern.html#gacb5843d0d5fd08d02fa4679b81b9d918">grppi::pipeline</a>(exec,</div><div class="line">  stageA,</div><div class="line">  stageB,</div><div class="line">  <a class="code" href="group__filter__pattern.html#gabc3773f21c14b2272c5ff404b4e9f8c2">grppi::keep</a>([](<span class="keyword">auto</span> x) { <span class="keywordflow">return</span> x.lenght()&gt;4; }),</div><div class="line">  stageC</div><div class="line">  );</div></div><!-- fragment --><hr/>
<p> <b>Note</b>: For brevity we do not show here the details of other stages.</p>
<p>For composing complex patterns, the <code><a class="el" href="group__filter__pattern.html#gabc3773f21c14b2272c5ff404b4e9f8c2" title="Invoke Filter pattern on a data stream that can be composed in other streaming patterns. This function keeps in the stream only those items that satisfy the predicate. ">keep()</a></code> and <code><a class="el" href="group__filter__pattern.html#gab8bcbdf6de8a446a291162ee4e7f7944" title="Invoke Filter pattern on a data stream that can be composed in other streaming patterns. This function discards from the stream those items that satisfy the predicate. ">discard()</a></code> functions may be used to create an object that may be supplied to another pattern to build a composed pattern. </p><hr/>
<p> <b>Example</b>: A composable filter stage in a pipeline. </p><div class="fragment"><div class="line"><span class="keyword">auto</span> keep_odd = <a class="code" href="group__filter__pattern.html#gabc3773f21c14b2272c5ff404b4e9f8c2">grppi::keep</a>(</div><div class="line">  [](<span class="keyword">auto</span> x) { <span class="keywordflow">return</span> x%2; });</div><div class="line"></div><div class="line"><a class="code" href="group__pipeline__pattern.html#gacb5843d0d5fd08d02fa4679b81b9d918">grppi::pipeline</a>(exec,</div><div class="line">  stageA,</div><div class="line">  stageB,</div><div class="line">  keep_odd,</div><div class="line">  stageC</div><div class="line">  );</div></div><!-- fragment --><hr/>
<p> <b>Note</b>: For brevity we do not show here the details of other stages. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>
